fix(ai): fold recased gateway-namespaced tool references onto request tools - #1489

Summary

Incident (2026-09-08, session 01a08016, omo 5.0.0-0.beta.48 / senpi 2026.9.7-2, claude-fable-5-1 through ccapi). A native tool search returned its tool_reference names both namespaced and recased: mcp__a4e6__Memory, mcp__a4e6__LspSymbols, mcp__a4e6__XSearch, mcp__a4e6__Eval for the request tools memory, lsp_symbols, x_search, eval (plus mcp__a4e6__cloudflare-docs_search_cloudflare_documentation, whose suffix stayed literal). Every later Anthropic request failed with Tool reference 'mcp__a4e6__Memory' not found in available tools and the session fell back to another model each turn (3 identical 400s in the transcript; the earlier attempts were masked by pool 429s, so the fallback/revert dance was a symptom, not the cause).

• The shipped engine (2026.9.7-2) predates fix(ai): fold gateway-namespaced Anthropic tool references onto the request's tools #1480, so it replayed the block verbatim -> 400.
• On main, fix(ai): fold gateway-namespaced Anthropic tool references onto the request's tools #1480's exact-suffix fold would have turned Memory into a dropped reference (Memory !== memory): no 400, but the discovery was lost and the search pair demoted to text.

Fix. resolveAvailableToolName now compares names with case and _/- separators folded away after the literal and namespace-stripped literal lookups fail. The folded index is built once per request from the tools array and drops any key that two request tools share, so the fold never guesses between candidates (such a reference stays unresolved and is dropped, as before). Same seam as #1480: the repair runs against the final tools array right before the SDK call.

Refactor (first commit, no behavior change). The tool-reference integrity pass was a fork-only block (since 5ecb30463) inside the 2.7k-line anthropic-messages.ts; it now lives in packages/ai/src/api/anthropic-tool-references.ts next to anthropic-tool-pairs.ts, and its suite is split into a shared harness (anthropic-tool-reference-harness.ts) plus one file per behavior cluster (client tool_reference/tool_use integrity; native tool-search replay). Fewer lines of fork-only code left in the upstream-shared file.

Tests

• test/anthropic-tool-reference-native-search.test.ts: recased namespaced native references fold onto memory / lsp_symbols / x_search (+ hyphenated literal kept); an ambiguous fold (x_search vs x-search) is dropped.
• test/anthropic-tool-reference-integrity.test.ts: a recased namespaced history tool_use (mcp__a4e6__XSearch) is renamed to x_search.

Evidence (mengmotaMac, fresh worktree, bun install --frozen-lockfile)

• RED (tests only on a1ac401): 3 failed / 10 passed - exactly the three new cases, assertion failures.
• GREEN: 13 passed across the two files. Mutations: identity fold -> 3 failed; ambiguity guard removed -> 1 failed (the ambiguity case); restored -> 13 passed.
• Incident replay: the real server_tool_use + tool_search_tool_result blocks from session 01a08016 through streamAnthropic with a capturing fake client -> all 8 references fold (memory, web_search, lsp_symbols, tool_search, cloudflare-docs_search_cloudflare_documentation, tool_search_tool_bm25, x_search, eval), 0 dangling.
• biome check on the 5 touched files: clean. Root tsc --noEmit: exit 0. scripts/check-pr-changelog.mjs: PASS.
• Full packages/ai vitest: 2594 passed / 0 failed; 1 pre-existing file load failure (test/codex-apply-patch-wire-schema.test.ts, @earendil-works/pi-tui entry unresolved in a fresh worktree - identical on the unpatched base, see fix(ai): fold gateway-namespaced Anthropic tool references onto the request's tools #1480).
• Rebased onto fix(ai,coding-agent): deliver Anthropic error status and recover a native tool-search 400 on the same model #1487 (cf2f61564); the only conflict was httpStatusOfError landing inside the moved block, kept in anthropic-messages.ts. Re-verification on the rebased commits is recorded in the PR comments.

Trackers

• packages/ai/src/changes.md (2026-09-08 entry) and packages/coding-agent/CHANGELOG.md [Unreleased] Fixed.

Summary by cubic

Fixes native tool-search references that the gateway hands back both namespaced and recased (mcp__a4e6__Memory for the request tool memory), which previously either hard-failed the request with Tool reference not found (forcing a weaker fallback model) or silently dropped the discovered tool. Tool-name matching now folds case and _/- separators after literal lookups fail, and only resolves a fold when exactly one request tool matches; ambiguous folds stay dropped.

Refactors

• Moves the tool-reference integrity pass out of anthropic-messages.ts into the new anthropic-tool-references.ts module.
• Splits the test suite into a shared harness plus one file per behavior cluster.

^{Written for commit 09ef716. Summary will update on new commits.}